docs(ai): connect-mcp — record what a first real connection actually hits - #16474
Merged
Conversation
baozhoutao
added
the
skip-changeset
github-actions
Bot
added
size/s
documentation
…hits Walked the page against a live app (Claude Code 2.1 + `@objectstack/mcp` 17.2) and wrote down the four places a first attempt stalls that the page did not cover: - OAuth track: after `claude mcp add`, `claude mcp list` reports "Failed to connect" until `/mcp` → Authenticate is done in a NEW session — the health probe is answered 401, not a broken setup. A running session never picks the server up. - API-key track: where the key is minted (Setup → Connect an Agent, page route, button at the bottom, shown once with a ready `x-api-key:` line), that a keyed registration shows "Connected" with no login, and that `claude mcp add` is local-scope by default (`-s user` for everywhere). - Verify: an anonymous curl that must return 401, and a keyed curl walk through initialize → tools/list → query_records, with the two gotchas that cost a retry — the argument is `objectName`, and its value is the API name from `list_objects` (`crm_opportunity`, not `opportunity`). - Troubleshooting: four rows for the above symptoms. Docs-only; publishes nothing. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
os-zhuang
approved these changes
Sep 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Walked
content/docs/ai/connect-mcp.mdxagainst a live app (Claude Code 2.1 +@objectstack/mcp17.2, HotCRM sample data) and wrote down the four places a first attempt stalls that the page did not cover. Docs-only; publishes nothing.What changed (one page)
claude mcp add,claude mcp list/claude mcp getreport ✘ Failed to connect until/mcp→ Authenticate is completed in a new session. The health probe is answered 401; the setup is not broken. A session already running when the server was added never picks it up.x-api-key:line, revoked under Setup → API keys); that a keyed registration shows ✔ Connected with no login step; thatclaude mcp addis local scope by default and-s usermakes it global.curlthat must return401, then a keyed walk throughinitialize→tools/list→tools/call query_records, with the two gotchas that cost a retry: the argument isobjectName, and its value is the API name fromlist_objects(crm_opportunity, notopportunity→Object 'opportunity' not found).Verification
check-docs-single-h1,check-docs-redirects,check-docs-image-tagall pass./docs/...link on the page resolves to an existing page.query_recordsoncrm_opportunityreturningtotal: 23).🤖 Generated with Claude Code